package com.thz.system.service.cos;

import org.springframework.web.multipart.MultipartFile;

import java.io.File;
import java.io.InputStream;

/**
 * COS文件服务接口
 * 
 * @author THZ
 * @date 2025
 */
public interface ICosFileService {
    
    /**
     * 上传文件到COS
     * 
     * @param file MultipartFile对象
     * @param prefix 存储路径前缀（如 uploads/, output/, avatars/）
     * @return 文件访问URL
     */
    String uploadFile(MultipartFile file, String prefix);
    
    /**
     * 上传本地文件到COS
     * 
     * @param localFile 本地文件
     * @param prefix 存储路径前缀
     * @return 文件访问URL
     */
    String uploadFile(File localFile, String prefix);
    
    /**
     * 上传输入流到COS
     * 
     * @param inputStream 输入流
     * @param fileName 文件名
     * @param prefix 存储路径前缀
     * @return 文件访问URL
     */
    String uploadFile(InputStream inputStream, String fileName, String prefix);
    
    /**
     * 删除COS上的文件
     * 
     * @param fileUrl 文件URL或key
     */
    void deleteFile(String fileUrl);
    
    /**
     * 下载文件到本地
     * 
     * @param fileUrl 文件URL或key
     * @param localFilePath 本地文件路径
     */
    void downloadFile(String fileUrl, String localFilePath);
    
    /**
     * 下载文件并返回输入流（用于代理访问）
     * 
     * @param fileUrl 文件URL或key
     * @return 文件输入流
     */
    InputStream downloadFile(String fileUrl);
    
    /**
     * 从URL中提取COS对象key
     * 
     * @param fileUrl 文件URL
     * @return COS对象key
     */
    String extractKeyFromUrl(String fileUrl);
    
    /**
     * 判断是否为COS URL
     * 
     * @param url URL字符串
     * @return true-是COS URL, false-不是
     */
    boolean isCosUrl(String url);
    
    /**
     * 获取文件的访问URL
     * 
     * @param key COS对象key
     * @return 文件访问URL
     */
    String getFileUrl(String key);
    
    /**
     * 安全下载文件并返回输入流（失败时返回null，不抛出异常）
     * 用于实现降级策略
     * 
     * @param fileUrl 文件URL或key
     * @return 文件输入流，失败时返回null
     */
    InputStream downloadFileSafely(String fileUrl);
}

